<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Administrative Functions</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Distributed Berkeley DB Applications" />
    <link rel="up" href="client.html" title="Chapter 3. Berkeley DB Client Driver APIs" />
    <link rel="prev" href="client.connectssl.html" title="Connecting to a Server with SSL" />
    <link rel="next" href="client.resource_api.html" title="Removing and Renaming Objects" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Administrative Functions</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="client.connectssl.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 3. Berkeley DB Client Driver APIs</th>
          <td width="20%" align="right"> <a accesskey="n" href="client.resource_api.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="client.admin_api"></a>Administrative Functions</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="client.admin_api.html#client.admin_api.servershutdown">Shutdown the Server</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="client.admin_api.html#client.admin_api.serverping">Using ping</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="client.admin_api.html#client.admin_api.serverversion">Getting the server version</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="client.admin_api.html#client.admin_api.closeHandle">Cleaning up Inactive Handles</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="client.admin_api.html#client.admin_api.deleteEnv">Deleting an Environment and Its Databases</a>
            </span>
          </dt>
        </dl>
      </div>
      <p> 
            Several functions are added to the client driver APIs to control
            the server, to clean up open handles and to delete unused
            environments. These functions do not rely on open handles and are
            put together into the <code class="classname">BdbServerAdmin</code> class.
        </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="client.admin_api.servershutdown"></a>Shutdown the Server</h3>
            </div>
          </div>
        </div>
        <p> 
                You can shutdown the server using the
                <code class="classname">shutdownServer</code> method: 
            </p>
        <pre class="programlisting">BdbServerConnection conn =
     BdbServerConnection.connect("localhost", 8080);

// Get an instance of the BdbServerAdmin class
BdbServerAdmin adminService = conn.adminService();

// Shutdown the server. After this method, close the connection.
adminService.shutdownServer();

// Close the connection.
conn.close();</pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="client.admin_api.serverping"></a>Using ping</h3>
            </div>
          </div>
        </div>
        <p>
                You can test the server's reachability using the
                <code class="classname">ping</code> method: 
            </p>
        <pre class="programlisting">BdbServerConnection conn =
     BdbServerConnection.connect("localhost", 8080);

// Get an instance of the BdbServerAdmin class
BdbServerAdmin adminService = conn.adminService();

// Test if the server is reachable. If the server is not
// reachable, an SDatabaseException is thrown.
adminService.ping();

...</pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="client.admin_api.serverversion"></a>Getting the server version</h3>
            </div>
          </div>
        </div>
        <p>
                You can get the version of Berkeley DB library used by the
                server using the <code class="classname">getServerBdbVersion</code>
                method: 
            </p>
        <pre class="programlisting">BdbServerConnection conn =
     BdbServerConnection.connect("localhost", 8080);

// Get an instance of the BdbServerAdmin class
BdbServerAdmin adminService = conn.adminService();

// Get the version of the Berkeley DB library used by the server.
String serverBdbVersion = adminService.getServerBdbVersion();

...</pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="client.admin_api.closeHandle"></a>Cleaning up Inactive Handles</h3>
            </div>
          </div>
        </div>
        <p> 
                Sometimes a handle may be left open for a long time on the
                server. This can be caused by a client application error, crash
                or hang. If this handle holds critical resources (e.g locks), it
                may slow down or even block other client applications.
            </p>
        <p>
                The Berkeley DB server can be configured to close these
                inactive handles periodically with the
                <code class="literal">cleanup.interval</code> and
                <code class="literal">handle.timeout</code> properties. For more
                information, see <a class="xref" href="config.html#server_conf" title="Server Configuration Options">Server Configuration Options</a>
            </p>
        <p> 
                In addition, the driver APIs also provide functions to clean
                up inactive environment and database handles. For example: 
            </p>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p>
                    When an environment or database handle is closed, all
                    handles that depend on it are also closed. For example,
                    when an environment handle is closed, all transaction
                    handles opened under the environment handles are also
                    closed. 
                </p>
        </div>
        <pre class="programlisting">BdbServerConnection conn =
     BdbServerConnection.connect("localhost", 8080);

// Get an instance of the BdbServerAdmin class
BdbServerAdmin adminService = conn.adminService();
<strong class="userinput"><code>
// Close handles opened on the environment whose home directory
// is "env", if they have not been accessed in the last 10 seconds.
adminService.closeEnvironmentHandles("env", 10 * 1000L);

// Close handles opened on the database specified with the given
// environment home directory, database file name and sub-database
// name, if they have not been accessed in the last 10 seconds.
adminService.closeDatabaseHandles("home", "dbFile", "subDb", 10 * 1000L);
</code></strong>
// Shutdown the server. After this method, close the connection.
adminService.shutdownServer();

// Close the connection.
conn.close();</pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="client.admin_api.deleteEnv"></a>Deleting an Environment and Its Databases</h3>
            </div>
          </div>
        </div>
        <p> 
                With the embedded Berkeley DB, you can remove an environment
                and all its databases by removing the environment home directory
                and any additional data, log and blob directories. The driver
                APIs also provide a way to do this: 
            </p>
        <pre class="programlisting">BdbServerConnection conn =
     BdbServerConnection.connect("localhost", 8080);

// Get an instance of the BdbServerAdmin class
BdbServerAdmin adminService = conn.adminService();
<strong class="userinput"><code>
// Delete the environment whose home directory is "env" and all the
// databases opened in it. Close all open handles on the environment
// and databases.
adminService.deleteEnvironmentAndDatabases("env", true);
</code></strong>
// Shutdown the server. After this method, close the connection.
adminService.shutdownServer();

// Close the connection.
conn.close();</pre>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="client.connectssl.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="client.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="client.resource_api.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Connecting to a Server with SSL </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Removing and Renaming Objects</td>
        </tr>
      </table>
    </div>
  </body>
</html>
